
\documentclass{l3deliverable}


\usepackage{url}
\usepackage{testcasedescription}%

\title{System Design}



%%authors
\author{ Melissa Campbell\\
Bilal Hamid\\
Jessica Bell\\
Tsvetelina Valcheva\\
John Martin
}

%%release date 
\date{\today}
\deliverableID{D8.1}
\project{PSD3 Group Exercise 2}
\team{E}
\version{2.3}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\maketitle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Standard section for all documents

\section{Introduction}
This is a finalised document which aims to outline a system design. The system design incorporates the requirements which we gathered from semester one and were revised from the feedback received. The test plan will describe test cases for each component, whilst we will also include an API specification for the interfaces realised by the components.

\subsection{Identification}

D8.1 is the System Design of the Level 3 Professional Software Development Team E.

\subsection{Related Documentation}

The documents related to this System Design and Acceptance Test plan are listed below.
\begin{list}{}{}
\item PSD3 Group Exercise Description \
  \url{http://fims.moodle.gla.ac.uk/}
  
\item D1: Team Management Document \
  \url{Team Google Documents Folder}
  
\item D2: Project Plan \
  \url{Team Google Documents Folder}
  
\item D3: Requirements Document \
  \url{Team Google Documents Folder}
  
\item D4: Prototyping Report\
  \url{Team Google Documents Folder}
  
\item D7: Implementation of DemoSocs Voting System \\
  \url{http://code.google.com/p/psd-team-project/}
  
\end{list}
 

\subsection{Purpose and Description of Document}
This document aims to outline both the overall system design for the voting system. The document consists of a component diagram showing the overall architecture of the system, followed by a set of class diagrams for each component and rationale describing the implementation.

\subsection{Document Status and Schedule}
The draft of the document was completed by the 26th of January. From this point onwards the document was continually updated as the architecture of the system is modified with the final revision completed by the 1st of March.

This is version 2.3 of the System Design document.

\section{System Design}

\subsection{Component Diagram}


\includegraphics[scale=0.6]{ComponentDiagram.PNG} 

\textbf{Rationale} \\

Our design centres around the following 4 components:

\begin{itemize}
\item Voting System Management
\item Election Object
\item Persistent Storage
\item Election System
\end{itemize}


The system design identified the Election Object component as encapsulating the information regarding an instance of an election whilst the Voting System Management component 
contains the functionality that manages an instance of an election. As a result separation of concerns is achieved - envisaging the Voting System Management component as a functional layer whilst the Election Object is the information layer. Consequently we also achieve information hiding. \\

The system design tries to obtain modularity as a way to protect other parts of the system from modification. \\


Furthermore the Voting System Management implements the provided Voting System facade through which a user interface or test harness can be connected to the system. The Voting System Management component contains a set of tools specific to the current format of an election. It interacts with the Election Object through an interface, ElectionManagement that allows for the creation, editing of elections, nominations and casting of votes. This interface also provides information about the election result and state. \\

The Election Object component is connected to the Election System component through the ElectoralSystem interface. \\

The Electoral System component was designed to handle all the different types of electoral systems as stated by the requirements. It was identified as a separate component because this allows the addition or removal of new election types using the Factory Pattern, thus taking into account volatile requirements. \\

The Persistent Storage component represents the system storage layer. It was designed as a separate component which can be easily replaced by the MyCampus service through the User Store interface. It provides two further interfaces for the Voting System Management component - the Election Store interface,  which provides functionality to save multiple election instances to an external archive, thus retaining information about the elections in the event of a system failure and providing a level of security. It also serves as an archive for past elections and results. Similar service is provided by the Electorate Store interface that retains information about electorates. \\

On the other side of this facade, a User Interface component is required to give access to a user to make use of the system and the log in and authentication of a user is handled by the given User Store interface to the Persistent Storage component.\\


\pagebreak 
\subsection{Class Diagrams}

%Election
\subsubsection{Election Object}
\includegraphics[scale=0.7]{electionObject.jpeg} 

\textbf{Rationale} \\

The above class diagram realises the Election Object component of the system design.

The ElectionImpl class implements the provided Election interface. It has methods for accessing the election start, end, nomination date and time. It also returns the list of approved candidates, election state and election result. Each election connects to an Electoral System interface, which allows the electoral type to be specified at creation and be connected to the corresponding system that is to be used to calculate the results. This approach allows any counting system to be used by the election class. For example, if "Single Plurality" is selected at the time of creating the election, the corresponding Electoral System will be Simple Plurality. Furthermore, each election instance has an instance of the Election State and the Election Result implementation. It also makes use of the implementation of the provided Candidate interface. 
It provides the ManageElection interface used by the Voting System Management component.\\

\pagebreak
%Storage
\subsubsection{Persistent Storage}
\includegraphics[scale=0.7]{storage.jpeg}

\textbf{Rationale}\\
The requirements state that the voting system must have functionality to retain election results and have different electoral types. As a result our Persistent Storage component provides 3 interfaces to access information about an election, validate a user and store users in different electorates. Since the MyCampus management system will not be ready to provide authentication information on users, our system is designed to readily integrate should this feature in supplied in the future. \\

Each interface in the Persistent Storage component provides methods to read and write data from an object file. Information was stored in object files to provide more security compared to plain text files, and if required the files could be encrypted to adhere to the non-functional requirement of "The system shall be sufficiently secure to withstand attack by an adversary with the same resources as a PSD project team", \textbf{[Requirements Specification Group Exercise 1]}. \\


% Election System
\subsubsection{Election System}
\includegraphics[scale=0.7]{ElectionSystem.jpeg}


\textbf{Rationale}\\ \\

The implementation makes use of the Election System component. This component provides the functionality to add or remove different election systems such as First Past the Post or Alternative Vote. The interface given provides methods to cast a vote and calculate the result of an election. The component also incorporates the Factory and Singleton design pattern. The Factory pattern was chosen since it provides the system with flexibility in adding new election types. This was particularly useful when the client requested that the voting system should have an ability to create referendums. \\

Furthermore the component connects to the Election Object component with the ElectoralSystem interface. In the ElectionImpl class an instance of ElectionSystem is stored where the singleton pattern ensures that each election can only have one instance of an electoral system.



%Voting System
\subsubsection{Voting System Management}

\includegraphics[scale=0.7]{VotingSystemManagement.jpeg} \\ \\

\textbf{Rationale} \\

The above class diagram realises the Voting System Management component of the system design.
VotingSystemImpl is the central class in the design as it accesses the storage, manages the current election and the actions available to the current user. 
VotingSystemImpl implements the VotingSystem interface and all corresponding methods. It provides additional methods to check whether the current user is election manager, as well as utility methods that print menues and initialise the current election.
It connects to the Election Object through the ElectionInterface, thus VotingSystemImpl does not know how Election is implemented.
Similarly, VotingSystemImpl initialises the UserStore, the ElectionStore and the ElectorateStore through their interfaces.


\subsection{Development Process}

The team decided that two members shall be developing the system whilst the other 3 will be responsible
for the testing process. The agile software development process was employed. This involved test first development, which %really?
was justified since it was easier to debug and prevent defects being introduced. \\

Due to a limited understanding of the system a pair programming approach was used. This was particularly beneficial in terms
of time saving and it prompted efficient development. If one member would be to implement a system feature by themselves, considerable time would have been lost in informing
the other member about any changes made to the system. This allowed the simultaneous development and inspection of the code.\\

However one particular disadvantage of this approach was that after the initial success the team became over confident and started making rash 
code changes without consideration of the consequences. \\

  

\subsection{API Specification}

\subsubsection{ElectoralSystem API}

\textbf{Full name:} public interface ElectoralSystem\\
\textbf{Package:} uk.ac.glasgow.demosocs.impl\\

The ElectoralSystem Interface provides functionality from the Election System component to the Election Object component. It provides methods to vote and get the result of the election while simultaneously hiding the actual calculation of the votes. \\

\textbf{Methods:}\\

\textbf{public String getName()} - this method returns the name of the Electoral System, for example Simple Plurality\\
\textbf{Return} - the name of the Electoral System\\

\textbf{public void vote (Vote v)} - this method represents the casting of a vote during an election\\
\textbf{Parameter} Vote v - this is an instance of a vote (could be a one of votes, ranked vote or a referendum vote)\\

\textbf{public ElectionResult getElectionResult()} - this implements the facade method and returns the winner of the election\\
\textbf{Return} - an instance of election result\\


\subsubsection{ManageElection API}

\textbf{Full name:} public interface ManageElection\\
\textbf{Package:} uk.ac.glasgow.demosocs.impl\\

The ManageElection Interface connects the Voting System Management component with the Election Object component. It provides functionality to Voting System Management to manage lists of candidates as well as the electorate, election state and electoral system associated with a specific Election Object.\\

\textbf{Methods:}\\


\textbf{public Set$<$Candidate$>$ getUnapprovedCandidates()} - this method returns a set of unapproved candidates (not accepted nomination)\\
\textbf{Return} - the set containing objects of type Candidate\\

\textbf{public Set$<$Candidate$>$ getApprovedCandidates()} - this method returns a set of approved candidates (accepted nomination)\\
\textbf{Return} - the set containing objects of type Candidate\\

\textbf{public String getElectorateName()} - this method returns a string containing the electorate name e.g. level3\\
\textbf{Return} String - name of electorate \\

\textbf{ElectoralSystem getElectoralSystem()} - this method returns the electorate system of an election e.g. AV or first past the post
\textbf{Return} ElectoralSystem - returns an instance of electoral system \\

\textbf{public void setElectionState(ElectionState s)} - Sets the election state e.g. to start, end or publish.\\
\textbf{Parameter} ElectionState - the state of an election.



\subsubsection{UserStore API}

\textbf{Full name:} public interface UserStore \\
\textbf{Package:} uk.ac.glasgow.demosocs.store\\

Hides the implementation of the UserStore and provides methods for accessing and adding users to the store. Used by the VotingSystemImpl class.\\


\textbf{Methods:}\\

\textbf{public void addUser(
			String surname, 
			String GUID, 
			String forename,
			String password)} Adds the new user to the store.\\

\textbf{Parameter} String surname  - the surname of the user\\
		   String GUID - the Glasgow University Identifier of the user \\
		   String forename - the forename of the user\\
		   String password - the password of the user\\

			
\textbf{public User getUser(String GUID, String password)}\\
\textbf{Return} the user specified by the GUID, id the authentication successful\\
\textbf{Parameter} String GUID - the Glasgow University Identifier of the user \\
 String password - the password of the user\\


						
\textbf{public User getUser(String GUID)}\\
\textbf{Return} the user specified by the GUID\\
\textbf{Parameter} String GUID - the Glasgow University Identifier of the user \\

\subsubsection{ElectionStore API}

\textbf{Full name:} public interface ElectionStore \\
\textbf{Package:} uk.ac.glasgow.demosocs.store\\

Hides the implementation of the ElectionStore and provides methods for accessing and adding Election objects to the store. Used by the VotingSystemImpl class.\\

\textbf{Methods:}\\
\textbf{public void addElection(ElectionImpl election)} - Adds an election to the election store file.\\
\textbf{Parameter} ElectionImpl election - the election object\\

\textbf{public ElectionImpl getElection(String electionId)} -  This method finds a specified election from the election store.\\
\textbf{Return} an election object identified by the electionId\\
 null if no election object matches the electionId\\

\textbf{Parameter} String electionId - the election id\\


\textbf{public Map$<$String, ElectionImpl$>$ getElections()} -  This method returns a maping from the electionId to the election object; the Map contains all elections found in the store.\\
\textbf{Return} maping from the electionId to the election object; the Map contains all elections found in the store.\\
null if no election objects in the store\\


\textbf{public void setElections(Map$<$String, ElectionImpl$>$ elections)} -  Populates the store with a maping from the electionId to the election object;\\
\textbf{Parameter} Map$<$String, ElectionImpl$>$ elections - maping from the electionId to the election object\\

\subsubsection{ElectorateStore API}

\textbf{Full name:} public interface ElectorateStore \\
\textbf{Package:} uk.ac.glasgow.demosocs.store\\

Hides the implementation of the ElectorateStore and provides methods for accessing, adding and removing users to the electorate as well as verifying if the user is part of the electorate. It also allows adding new electorate as well as verifying that the electorate is valid. Used by the VotingSystemImpl class.\\

\textbf{Methods:}\\

\textbf{public abstract void addElectorate(String electorateID,
			HashSet$<$String$>$ users)} - adds the electorate specified by the electorateID to the store; the electorate consists of the users in the hashset - the hashset stores the GUID of the users.\\ 
			
textbf{Parameter} String electorateID - identifies the electorate, for example "Level3"\\
HashSet$<$String$>$ users - the users to be considered part of the electorate, stored by their GUIDs\\


\textbf{public abstract void addElectorate(String electorateID)} - Adds a new electorate to the storage\\
textbf{Parameter} String electorateID - identifies the electorate, for example "Level3"\\


\textbf{public abstract void addUserToElectorate(String electorateID, String userID)} - Adds a user to an electorate\\
\textbf{Parameter} String electorateID - identifies the electorate, for example "Level3"\\
String userID - user's GUID\\

\textbf{public abstract void removeUserFromElectorate(String electorateID,
			String userID)} - Removes a user from an electorate\\
\textbf{Parameter} String electorateID - identifies the electorate, for example "Level3"\\
String userID - user's GUID\\


\textbf{public abstract boolean isEligible(String electorateID, String userID)} - Checks if a particular user is part of the specified electorate \\
\textbf{Return} true if user is part of electorate\\
false if user is not part of electorate\\
\textbf{Parameter} String electorateID - identifies the electorate, for example "Level3"\\
String userID - user's GUID\\

\textbf{public abstract boolean isValidElectorate(String electorateName))} - Checks if the specified electorate exists in the store \\
\textbf{Return} true if the electorate exists in the store\\
false if the electorate does not exist in the store\\
\textbf{Parameter} String electorateID - identifies the electorate, for example "Level3"\\


\end{document}
